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FOREWORD 


This  research  and  development  was  conducted  under  contract  #N00123-81-D0794 
with  Bolt  Beranek  and  Newman,  Inc.  in  support  of  Navy  Decision  Coordinating  Paper 
Z1177-PN  (Advanced  Computer-Aided  Instruction),  subproject  Z1177-PN.03  (STEAMER; 
Advanced  Computer-Based  Training  for  Propulsion  and  Problem  Solving).  It  was  sponsored 
by  the  Chief  of  Naval  Operations  (OP-01).  The  main  objective  of  the  STEAMER  effort  is 
to  develop  and  evaluate  advanced  knowledge-based  techniques  for  use  in  low-cost  portable 
training  systems.  The  project  is  focused  on  propulsion  engineering  as  a  domain  in  which  to 
investigate  these  computer-based  training  techniques. 

This  report,  the  second  in  a  series  on  the  STEAMER  project,  documents  the  general 
graphics  software  used  for  presenting  diagrams  and  accepting  input  from  users  of  the 
system.  The  first  report  (NPRDC  TN  81-21)  provided  a  taxonomy  for  generating  explana¬ 
tions  of  how  to  operate  complex  physical  devices.  Intended  users  of  these  reports  are 
system  maintainers  and  other  research  personnel. 

The  contracting  officer's  technical  representative  was  Dr.  3ames  Hollan. 

JAMES  F.  KELLY,  JR.  JAMES  J.  REGAN 

Commanding  Officer  Technical  Director 
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SUMMARY 


Problem 

The  main  objective  of  the  STEAMER  effort  is  to  develop  and  evaluate  advanced 
knowledge-based  techniques  for  use  in  low  cost  portable  training  systems.  The  project  is 
focused  on  propulsion  engineering  as  a  domain  in  which  to  investigate  these  computer- 
based  training  techniques.  The  basic  design  of  the  STEAMER  system  includes  a 
mathematical  model  of  a  propulsion  plant  that  students  and  instructors  inspect  and 
control  using  diagrams  presented  on  a  color  graphics  display. 

Objective 

The  objective  of  this  effort  was  to  document  the  general  software  used  to  present, 
create,  and  display  diagrams  and  accept  input  from  users  of  STEAMER.  This 
documentation  is  intended  as  a  reference  manual  for  those  who  write  STEAMER  software. 
Software  Documentation 

The  STEAMER  hardware  consists  of  a  color  graphics  terminal,  a  text  terminal,  and 
several  graphical  input  devices.  The  graphics  output  software  is  organized  in  terms  of 
four  levels:  (1)  a  level  that  mirrors  precisely  the  graphics  terminal  functionality,  (2)  a 
level  that  provides  user-defined  coordinate  mappings,  (3)  a  level  modelled  after  LOGO 
graphics  that  preserves  the  state  of  an  abstract  object  called  a  "turtle,"  and  (4)  the 
topmost  level,  which  includes  a  library  of  graphics  objects  such  as  pumps,  graphs,  gauges, 
pipes,  and  valves  for  constructing  diagrams.  The  graphics  input  software  allows  the 
programmer  to  define  abstract  input  devices  and  mappings  between  the  input  device  and 
the  screen. 

Applications 

Organizing  the  system  in  this  way  has  permitted  the  building  of  a  graphics  editor  to 
manipulate  graphics  objects  so  that  diagrams  can  be  rapidly  created.  The  abstract  input 
device  concept  allows  easy  experimentation  with  different  interactive  input  devices.  No 
software  modifications  are  needed  for  the  user  to  change  from  using  a  transparent  touch 
panel  to  using  the  terminal  joystick  or  even  a  keyboard. 
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APPENDIX  OOi:UM  STATION  OF  STEAMER  SOFTWARE  FUNCTIONS 


INTRODUCTION 


Problem 

The  main  objective  of  the  STEAMER  effort  is  to  develop  and  evaluate  advanced 
knowledge-based  techniques  for  use  in  low  cost  portcdile  training  systems.  The  project  is 
focused  on  propulsion  engineering  as  a  domain  in  which  to  investigate  these  computer- 
based  training  techniques.  The  basic  design  of  the  STEAMER  system  includes  a 
mathematical  model  of  a  propulsion  plant  that  students  and  instructors  inspect  and 
control  using  diagrams  presented  on  a  color  graphics  display. 

Objective 

The  objective  of  this  effort  was  to  document  the  general  software  used  to  present, 
create,  and  display  diagrams  and  accept  input  from  users  of  STEAMER.  This  documen¬ 
tation  is  intended  as  a  reference  manual  for  those  who  write  STEAMER  software. 

RESULTS 

Four  major  packages  of  software  are  described  in  this  section.  These  are  the  AED 
driver,  the  graphics  library,  turtle  graphics,  and  the  graphical  input  package. 

The  AED  driver  provides  a  set  of  functions  that  enable  opening  and  closing  I/O, 
writing  pixel  values,  manipulating  masks,  and  manipulating  color  look-up  tables.  The 
graphics  library  provides  a  set  of  function-supporting  general  coordinate  system  transfor¬ 
mations  and  additional  utilities.  The  turtle  graphics,  modelled  after  the  LOGO  turtle, 
provides  the  highest  level  of  available  functionality  by  supporting  an  abstract  "turtle"  that 
maintains  a  state  defined  by  its  location,  heading,  and  pencolor.  Finally,  the  graphical 
input  package  provides  a  uniform  interface  over  a  variety  of  devices.  Two  types  of  input 
are  supported,  button  and  locator,  in  a  fashion  roughly  analogous  to  the  SIGGRAPH  Core 
Graphics  System. 

The  AED  Driver 

This  section  describes  the  AED  driver  calls  that  are  concerned  with  opening  and 
closing  I/O,  pixel  writing  values,  masks,  and  color  look-up  table  manipulation.  All 
arithmetic  is  in  fixed  point. 


The  AED  video  output  is  a  two-dimensional  array  of  picture  elements,  or  pixels. 
Pixels  are  the  quanta  of  the  image,  the  smallest  portion  of  image  area  that  the  AED  can 
control.  Reflecting  this,  the  frame  buffer  memory  is  a  two-dimensional  array,  with  eight 
bits  in  each  array  element  representing  a  pixel. 

The  color  of  a  pixel  in  the  image  is  determined  by  using  the  eight-bit  pixel  value 
(pixval)  as  an  index  into  a  "color  table."  A  color  table  consists  of  256  "slots,"  one  slot  for 
each  possible  pixval.  A  slot  contains  a  red,  green,  and  blue  (RGB)  value  that  describes  the 
color  to  be  displayed. 

The  AED  maintains  three  internal  parameters  that  govern  all  frame  buffer  write 
operations,  the  write  mask,  the  draw  value,  and  the  background  value.  (The  current 
values  of  these  parameters  are  stored  in  the  free  variables  "aed;swm,"  "aedtsec,"  and 
"aed:sbc"  respectively.)  When  a  draw  command  (vector,  circle,  etc)  is  issued  to  the  AED, 
the  appropriate  pixels  are  selected  for  updating.  If  the  Nth  bit  of  the  write  mask  is  on, 
then  the  Nth  bit  of  each  selected  pixel  will  be  replaced  with  the  Nth  bit  of  the  draw 
value.  If  the  write  mask  bit  is  off,  the  corresponding  pixel  bit  is  not  changed.  The 
background  value  is  used  in  a  similar  fashion,  but  only  during  a  screen  clear  (the  "aed:clr" 
function). 

The  file  "aedidcls"  contains  compiler  declarations  for  the  AED  functions.  These 

functions  are  summarized  below  and  documented  in  the  appendix.  The  documentation 

includes  a  description  of  the  function,  the  arguments  it  takes  and  the  argument  types,  and 

any  relevant  notes  about  the  function.  Unless  stated  otherwise,  functions  always  return  a 

value  of  "t." 

aed:black-ct 

aedrclose 

aediclr 

aed:copy-ct 

aed:create-ct 

aed:date-time 

aed:dump-ct 

aed;get-cts-list 

aed:gray-ct 

aed:load-ct 
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The  graphics  library  (GL)  has  several  objectives: 

1.  Providing  a  level  of  functionality  somewhat  higher  than  the  AED  driver. 

2.  Supporting  arbitrary  coordinate  systems  in  floating  point,  which  also  provides 
some  measure  of  device  independence. 

3.  Collecting  miscellaneous  graphics  utilities. 

4.  Supporting  graphics  classes. 

The  GL  package  allows  one  to  define  an  arbitrary  coordinate  system  that  is  then 
mapped  into  the  AED  coordinates.  Two-dimensional  coordinate  transformations,  including 
scaling  translation  and  rotation,  are  supported  using  the  standard  3x3  matrix  scheme. 
The  matrices  are  Lisp  objects  that  can  be  lambda-bound  using  a  supplied  macro. 
Subregions  defined  with  respect  to  a  coordinate  system  can  be  given  their  own  local 
coordinate  system  so  that  all  references  within  them  are  in  convenient  coordinates. 

The  "current  address  position"  (CAP)  is  the  position  where  the  AED  "pen"  was  last 
left.  Many  functions  use  the  CAP  as  a  starting  point  for  efficiency  purposes.  Unless 
otherwise  stated,  function  calls  do  not  modify  the  CAP. 

The  file  "gltdcls"  contains  complier  declarations  for  the  GL  functions.  These 
functions  are  summarized  below  and  documented  in  the  appendix.  The  documentation 


includes  a  description  of  the  function,  the  arguments  it  takes  and  the  argument  types,  and 
any  relevant  notes  about  the  function.  Unless  stated  otherwise,  functions  always  return  a 
value  of  "t." 
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ghboxrel 
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gl:ecu 

ghfindy 

ghidiv^ 

gl:ifl 
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gl:line 

gUlinerel 

gl:map-coordinates 

gl:map-standard-coordlnates 

gl:mod$ 

ghmov 

ghmovrel 

ghpoint 

gl;refiect-x 

gl:reflect-y 

ghrestore-coordinates 

ghrotate 
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gl:solidbox 

ghsolidboxrel 

glzsolidcircle 

ghtransform-coordinate 

gUwritetext 

By  convention,  four  variables,  "xl,"  "yb,"  "xr,"  and  "yb"  are  used  to  describe 
rectangular  regions,  where  "xl"  is  the  x  coordinate  of  the  left  side  of  the  region,  "yb"  is 
the  y  coordinate  of  the  bottom  side,  "xr"  is  the  x  coordinate  of  the  right  side,  and  "yt"  is 
the  y  coordinate  of  the  top  side. 

The  Turtle  Graphics  Interface 

This  section  describes  the  turtle  graphics  interface.  Calls  to  turtle  graphics 


functions  may  be  freely  intermixed  with  calls  to  the  AED  and  GL  packages. 


All  arithmetic  is  in  floating  point,  and  the  turtle  coordinate  system  ranges  from  (0.0, 
0.0)  at  the  lower- left  corner  to  (1.0,  1.0)  at  the  upper-right.  No  error  checking  is 
performed,  so  coordinates  outside  this  range  will  cause  trouble. 

The  state  of  the  turtle  is  maintained  in  several  free  variables.  These  variables  may 
be  evaluated,  SETQed,  or  lambda-bound  at  any  time.  In  addition,  each  variable  has  a 
function  of  the  same  name  that  returns  the  variable's  current  value.  The  variables  are 
listed  below: 

1.  heading  is  the  direction  of  the  turtle  in  degrees.  0.0  degrees  corresponds  to  the 
+X  direction,  90.0  to  +Y  (i.e.,  heading  ir>creases  counterclockwise). 

2.  pencolor  is  the  color  of  the  turtle  pen.  Pencolors  currently  supported  are  black, 
red,  green,  yellow,  blue,  magenta,  cyan,  and  white. 

3.  penstate  is  "t"  if  the  pen  is  down,  "nil"  if  it  is  up. 

4.  screencolor  is  the  color  the  screen  will  be  cleared  to  by  a  "clearscreen"  call. 
The  pencolor  should  equal  the  screencolor  to  make  the  turtle  "erase." 

5*  turtlestate  is  "t"  if  the  turtle  cursor  is  visible,  "nil"  if  it  is  invisible. 

6.  xcoord  is  the  turtle  x  position. 

7.  ycoord  is  the  turtle  y  position. 

The  file  "turtle:dcls"  contains  compiler  declarations  for  the  turtle  functions.  These 

functions  are  summarized  below  and  documented  in  the  appendix.  The  documentation 

includes  a  description  of  the  function,  the  arguments  it  takes  and  the  argument  types,  and 

any  relevant  notes  about  the  function.  Unless  stated  otherwise,  functions  always  return  a 

value  of  "t." 
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Graphical  Input 

The  graphical  input  package  provides  a  uniform  interface  over  a  variety  of  devices. 
Two  types  of  input  are  supported,  button  and  locator,  in  a  fashion  roughly  analogous  to  the 
SIGuRAPH  Core  Graphics  System, 

Locator  devices,  such  as  the  Summagraphics  tablet,  or  the  Biographies  touch  screen, 
report  a  position  specified  by  the  user.  The  full  range  of  the  locator  device  is  mapped 
onto  the  current  GL  coordinate  system  extents. 

Button  devices  report  a  value  representing  the  status  of  a  button  or  set  of  buttons. 
Button  values  vary  somewhat  between  the  various  physical  devices.  However,  they  all 
return  "0"  when  "not  depressed,"  so  this  fact  may  be  used  for  simple  predicate  testing. 


The  file  "gi:dcls"  contains  the  compiler  declarations  for  the  graphical  input  functions. 
These  functions  are  summarized  below  and  documented  in  the  appendix.  The  documen- 


tation  includes  a  description  of  the  function,  the  arguments  it  takes  and  the  argument 
types,  and  any  relevant  notes  about  the  function.  Unless  stated  otherwise,  functions 

always  return  "t." 
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AED  Driver 


aed; black-ct 


Description 


aed: black-ct 


The  aed: black-ct  function  sets  all  the  RGB  values  in  a  color 
table  to  zero. 

Usage 


(declare  (notype  (aed:black-ct  notype) ) ) 


(aed; black-ct  ct) 


where: 

1.  ct  is  a  color  table. 

2.  return  value  is  ct. 


Motes 


The  color  table  is  not  transmitted  to  the  AED. 


See  the  aed:create-ct  function. 
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aed: close 


aed: close 


Description 

The  aed: close  function  closes  AED  I/O. 

Usage 

(declare  (notype  (aediclose) ) ) 

(aed: close) 
where: 

1.  return  value  is  "t"  if  AED  I/O  was  closed, 
I/O  was  already  closed. 


"nil"  if  AED 


A-2 


The  aed;copy-ct  function  copies  contiguous  sections  of  color 
table  slots  from  one  color  table  to  another. 

Usage 

(declare  (notype  (aed:copy-ct  notype  fixnum  notype  f ixnum) ) ) 
(aed:copy-ct  ct-from  start-from  ct-to  start-to  count) 
where: 


1. 

ct-from  is  the  source  color  table. 

2. 

start-from  is  the  first  slot  to 
source  color  table. 

be  copied 

from  the 

3, 

ct-to  is  the  target  color  table. 

4. 

start-to  is  the  first  slot  to  be  updated  in 
color  table. 

the  target 

5. 

count  is  the  number  of  slots  to  be 

copied. 

Notes 


The  same  color  table  may  be  used  as  source  and  target. 


aed;create-ct 

Description 

The  aed:create-ct  function  creates  a  new 
initialized  to  all  zeros  (black) . 

Usage 

(declare  (notype  (aed;create-ct) ) ) 

(aed;create-ct) 

where : 


aed;create-ct 


color  table. 


1. 


return  value  is  the  new  color  table 
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aed; date-time 


Description 


aed; date-time 


The  aed;date-time  function  prints  the  current  date  and  time 
in  large  letters  on  the  AED.  This  is  useful  for  dating  video 
tapes. 


Usage 


(declare  (notype  (aed; date-time) ) ) 


(aed; date- time) 


aed;duinp-ct  aed;dump 

Description 

The  aed;dump-ct  function  writes  a  color  table  to  a  file. 
Usage 

(declare  (notype  (aed:dump-ct  notype  no type) ) ) 

(aed; dump-ct  ct  filespec) 
where: 

ct  is  the  color  table  to  be  dumped. 

filespec  is  the  file  to  be  written  in  Maclisp  filespec 
format.  A  "mergef"  is  performed  on  filespec  and  "((* 
*)  *  ct) "  to  obtain  the  final  filename. 

Notes 


-ct 


See  the  aed:load-ct  function 


Description 

The  aed:get-cts-list  function  returns  the  contents  of  a  color 
slot  as  a  list. 

Usage 

(declare  (notype  (aed:get-cts-list  notype  fixnum))) 

(aed;get-cts-list  ct  slot) 

where; 

1.  ct  is  a  color  table. 

2.  slot  is  the  number  of  the  slot. 

3.  return  value  is  a  list,  "(R  G  B)". 


Notes 


See  the  aed;put-cts-list  function 


aed;qray~ct 


aed;qray-ct 


Description 

The  aed:gray-ct  function  sets  a  color  table  to  a  256  slot 
gray  scale. 

Usage 

(declare  (notype  (aed;gray-ct  no type) ) ) 

(aed:gray-ct  ct) 
where: 

1.  ct  is  a  color  table. 

2.  return  value  is  ct. 


Notes 


See  the  aed:create-ct  function 


Description 

The  aed:load-ct  function  loads  a  color  table  from  a  file. 
Usage 

(declare  (notype  (aed:load-ct  notype  no type) ) ) 
(aed:load-ct  ct  filespec) 


where; 

ct  is  an  existing  color  table  that  the  file  will  be 
read  into. 

filespec  is  the  file  to  be  read  in  Maclisp  filespec 
format.  A  "mergef"  is  performed  on  filespec  and  "((* 
*)  *  ct) "  to  obtain  the  final  filename. 


Notes 


See  the  aed;dump-ct  function 


The  aed: put-cts-list  function  sets  a  color  table  slot. 


Usage 

(declare  (notype  (aed:put-cts-list  notype  fixnum  notype) ) ) 

(aed;put-cts-list  ct  slot  list) 

where: 

ct  is  a  color  table. 

slot  is  the  slot  number  to  be  set. 

list  is  a  list,  "  (R  G  B)",  of  the  new  color  slot 
values. 

Notes 

See  the  aed:get-cts-list  function. 


The  aed:open  function  will  open  AED  I/O,  only  if  it  is  not 
already  open. 

Usage 

(declare  (notype  (aedropen))) 

( aed; open) 
where: 

1.  return  value  is  "t"  if  AED  I/O  was  opened,  "nil"  if  AED 
I/O  was  already  open. 

Notes 

The  free  variable  "aedtopen?" 
otherwise  it  is  "nil". 


is  "t"  if  the  AED  is  open. 


aed: reset 


aed; reset 


Description 

The  aed: reset  function  flushes  all  pending  AED  I/O,  and 
initalizes  the  AED. 

Usage 

(declare  (notype  (aed: reset) ) ) 

(aed: reset) 

Notes 


Aed: reset  takes  approximately  two  seconds  to  complete. 


aed; rotate-cts-down 


aed; rotate-cts-down 


Description 

The  aed: rotate-cts-down  function  rotates  a  contigious  segment 
of  color  table  slots  down  by  one  slot,  with  the  bottom  slot  going 
to  the  top  slot. 

Usage 

(declare  (notype  (aed: rotate-cts-down  notype  fixnum  f ixnum) ) ) 
(aed; rotate-cts-down  ct  start  length) 


i.-: 
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where; 

1.  ct  is  a  pointer  a  color 

2.  start  is  the  first  slot 

3 .  length  is  the  number  of 


table. 

in  the  segment  to  be  rotated 
slots  to  be  rotated. 
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aed: sbc 


aed: sbc 


Description 

The  aed: sbc  function  sets  the  value  that  the  AED  memory  will 
be  set  to  after  a  call  to  the  "aed:clr"  function. 

Usage 


(declare  (notype  (aedtsbc  fixnum) ) ) 

(aed: sbc  pixval) 

where: 

1.  pixval  is  the  pixel  value. 

Notes 


See  the  aed:clr  and  aed:swm  functions. 
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aed; sbl  aed; sbl 

Description 

The  aed: sbl  function  sets  up  the  AED  such  that  a  pixel  value 
maps  alternately  thru  the  AED  color  table  and  a  new  set  of  RGB 
values,  producing  a  blink  effect. 

Usage 

(declare  (notype  (aed: sbl  fixnum  fixnum  fixnum  fixnum  fixnum 
f ixnum) ) ) 


i 


(aed: sbl  pixval  r  g  b  current  new) 
where: 


1. 

pixval  is  the  pixel  value  to  be  blinked. 

2. 

£  is  the  new  red  map  value. 

3. 

£  is  the  new  green  map  value. 

4. 

b  is  the  new  blue  map  value. 

5. 

old  is  the  number  of  fields  that 
taEle  will  be  used  to  map  pixval. 

the 

current  color 

6. 

new  is  the  number  of  fields  that  the 
be  used  to  map  pixval. 

RGB 

arguments  will 

Notes 


Up  to  eight  pixel  values  can  be  blinked  simultaneously. 


The  AED  color  table  is  not  changed 
A  field  is  l/60th  of  a  second. 

See  the  "aed: sbl-of f "  function. 


by  this  function. 
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aed: sbl-of f 


Description 


aed; sbl-of f 


The  aed: sbl-of f  function  stops  blinking  started  by  the 
aedrsbl"  function. 


Usage 

(declare  (notype  (aed;sbl-off  f ixnum) ) ) 

(aed: sbl-of f  pixval) 

where; 


1.  pixval  is  the  pixel  value  which  should  no  longer  blink 


aed: see 


aed: sec 


Deseription 

The  aed; see  funetion  sets  the  pixel  value  that  the  eursor 
will  use. 

Usage 

(deelare  (notype  (aed: see  fixnum  fixnum  fixnum) ) ) 

(aed; see  pvl  pv2  blink-time) 

where; 

1.  pvl ,  pv2  are  pixel  values. 

2.  blink-time  is  in  units  of  l/60th  of  a  seeond. 

Notes 

The  eursor  will  use  pvl  for  for  the  interval  specified  by 
ulink-time,  then  pv2,  then  pvl  again,  etc.  If  blinking  is  not 
desired,  pvl  and  pv2  should  be  equal. 


aed; scp+ 

Description 

The  aed:scp+  function  instructs  the  AED  to  use  a 
cursor . 

Usage 

(declare  (notype  (aed:scp+))) 


aed;  scp-f 


shaped 


(aed; scp+) 


aed; scpx  aed; scpx 

Description 

The  aed:  scpx  function  instructs  the  AED  to  use  a  "x"  shaped 
cursor . 

Usage 

(declare  (notype  (aed: scpx))) 

(aed: scpx) 


aed: set 


aed: set 


Deser iption 

The  aed; set  funetion  transmits  segments  of  a  eolor  table  to 
the  AED. 

Usage 

(deelare  (notype  (aed; set  notype  fixnum  fixnum) ) ) 

(aed; set  ct  start  eount) 
where; 

1.  ct  is  a  color  table. 

2.  start  is  the  first  slot  to  be  transmitted. 

3.  count  is  the  number  of  slots  to  be  transmitted. 


aed: sctl 


aed: sctl 


Description 

The  aed; sctl  function  updates  one  slot  of  a  color  table,  and 
transmitts  the  new  slot  to  the  AED. 

Usage 

(declare  (notype  (aed: sctl  notype  fixnum  fixnum  fixnum 
f ixnum) ) ) 

(aed; sctl  ct  slot  r  g  b) 
where; 

1.  ct  is  a  color  table. 

2.  slot  is  the  slot  to  be  updated. 

3.  r  is  the  red  value. 

4.  3  is  the  green  value. 

5.  b  is  the  blue  value. 
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Descr iption 

The  aed; sctl-list  function  updates  one  slot  a  color  table  and 
transmitts  the  new  slot  to  the  AED. 

Usage 

(declare  (notype  (aed; sctl-list  notype  fixnum  notype))) 

(aed: sctl-list  ct  slot  list) 
where: 

1.  ct  is  a  color  table. 

2.  slot  is  the  slot  to  be  updated. 


3.  list  is  a  list 


"(R  G  B)",  of  the  new  slot  values 


aed: sec 


aed: sec 


Description 

The  aed; sec  function  sets  the  draw  pixel  value. 
Usage 

(declare  (notype  (aed: sec  fixnum))) 

(aed: sec  pixval) 
where: 

1.  pixval  is  the  new  draw  value. 

Notes 


The  pixel  value  actually  written  depends  both  on  the 
value  and  the  write  mask.  See  the  introduction  and  the  aediswm 
function. 
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aed; sis  aed; sis 

Description 

The  aed: sis  function  sets  specifies  a  broken  line  template. 
Usage 

(declare  (notype  (aedtsls  fixnum  fixnum) ) ) 

(aed: sis  template  scale) 


where : 

1.  template  is  a  binary  encoding  of  the  line  template, 
with  "1"  bits  corresponding  to  visible  portions  of  the 
line  and  "0"  bits  to  invisible  portions.  Template  =  255 
will  yield  solid  lines. 

2.  scale  is  a  scale  factor  for  the  template,  and  can  be  1, 
2 ,  4 ,  or  8 . 


aed: swm 


aed: swm 


Description 

The  aed: swm  function  sets  the  AED  write  mask,  which  governs 
all  write  operations  into  AED  memory. 

Usage 

(declare  (notype  (aed: swm  f ixnum) ) ) 

(aed: swm  mask) 
where: 

1.  mask  is  the  new  write  mask. 
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il; bind-coordinates 


Description 


|1: bind-coordinates 


The  gl : bind-coordinates  macro  lambda  binds  a  new  mapping 
matrix.  Functions  inside  the  macro  body  see  the  new  matrix,  and 
may  modify  it  destructively.  When  the  macro  returns,  the  new 
matrix  is  popped,  and  the  matrix  which  existed  prior  to  the 
gl: bind-coordinates  call  is  restored. 

Usage 

(gl: bind-coordinates  forml  form2  ...  formN)  where: 

formi  is  any  lisp  form. 


1.  return  value  is  the  value  of  formN. 


Notes 


See  the  gl: save-matrix  and  gl: restore-matr ix  functions. 


gl; box  ql; box 

Description 

The  glzbox  function  draws  the  perimeter  of  a  rectangle.  One 
corner  of  the  rectangle  is  at  the  CAP,  and  the  opposite  corner  is 
at  a  specified  position. 

Usage 

(declare  (notype  (glzbox  flonum  f lonum) ) ) ) 

(glzbox  X  y) 
where z 

1.  X  is  the  X  coordinate  of  the  corner  opposite  the  CAP. 

2.  Y  is  the  y  coordinate  of  the  corner  opposite  the  CAP. 

Notes 


The  CAP  is  unchanged. 


h.O 
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gl; boxrel 


Description 


gl; boxrel 


The  gl; boxrel  function  draws  the  perimeter  of  a  rectangle. 
One  corner  of  the  rectangle  is  at  the  CAP,  and  the  opposite 
corner  is  determined  by  the  length  of  the  rectangle's  sides. 

Usage 

(declare  (notype  (gl;boxrel  flonum  f lonum) ) ) 


(gltboxrel  dx  dy) 


where: 

1.  ^  is  the  length  of  the  horizontal  side. 

2.  ^  is  the  length  of  the  vertical  side. 

Notes 

The  CAP  is  unchanged. 


Dx  and  dy  may  be  negative 


gltcircle  glzcircle 

Description 

The  gltcircle  function  draws  the  perimeter  of  a  circle.  The 
center  of  the  cir'^le  is  the  CAP. 

Usage 

(declare  (notype  (gltcircle  f lonum) ) ) 

(gltcircle  radius) 
wheret 

1.  radius  is  the  radius  of  the  circle. 


Notes 


The  CAP  is  unchanged 


The  gl:dca  function  sets  the  CAP  at  a  specified  position,  and 
turns  on  the  cursor  there. 

Usage 

(declare  (notype  (gl:dca  flonum  f lonum) ) ) 

(glidca  X  y) 
where; 

1.  X  *  position  of  the  cursor. 

2.  Y  is  the  y  position  of  the  cursor. 

Notes 

See  the  gliecu  function. 

Due  to  a  feature/bug  in  the  AED,  the  cursor  must  be  turned 
off  before  calling  any  function  that  does  drawing. 


ql; ecu  ql; ecu 

Descr iption 

The  qltecu  function  turns  the  AED  cursor  off. 

Usaqe 

(declare  (notype  (glrecu))) 

(gl : ecu) 
where: 

Notes 


See  the  gl:dca  function. 


ql;findy  gltfindy 

Description 

The  gltfindy  function,  given  two  points  which  define  a  line 
and  an  x  value,  computes  y  such  that  (x,y)  is  on  the  line. 

Usage 

(declare  (notype  (gl:findy  flonum  flonum  flonum  flonum 
f lonum) ) ) 

(glifindy  xline  yline  xline2  yline2  x) 


where: 

1.  (xline, yline)  is  a  point  on  the  line. 

2.  (xline2,yline2)  is  a  second  point  on  the  line. 

3.  X  *  value  of  a  point  of  the  line. 

4.  return  value  is  the  y  value  corresponding  to  x. 


gl;  ifl  gl-«  ifl 

Description 

The  gltifl  function  fills  a  closed  region.  The  CAP  is  a 
point  inside  the  region,  and  the  boundary  is  defined  by  pixels 
whose  values  differ  from  the  value  of  the  pixel  at  the  CAP. 

Usage 

(declare  (gl; ifl) ) 

(gl: ifl) 
where; 

Notes 
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The  gl; in-region  function  determines  whether  a  point  is 
inside  a  rectangular  region. 

Usage 

(declare  (notype  (gl; in-region  flonum  flonum  flonum  flonum 
flonum  flonum) ) ) 

(gl: in-region  xl  yb  xr  yt  xpt  ypt) 
where: 

1.  xl ,  yb,  xr ,  yt  defines  the  region. 

2.  xpt  is  the  x  coordinate  of  the  point  to  be  tested. 

3.  ypt  is  the  y  coordinate  of  the  point  to  be  tested. 


4. 


return  value  is  "t"  if  the  point  is  inside  the  region, 
otherwise  "nil" . 


il:  line 


Descr iption 


}1:  line 


The  gl;line  function  draws  a  line  from  the  CAP  to  the 
position  specified. 


Usage 


(declare  (notype  (gl;line  flonum  f lonum) ) ) 


(glzline  x  y) 


where: 


1.  X  is  the  X  position  of  the  second  endpoint. 

2.  Y  is  the  y  position  of  the  second  endpoint, 


Notes 


The  new  CAP  is  (x,y). 


ql; map-coordinates  gl; map-coordinates 

Description 

The  gl: map-coordinates  function  modifies  the  mapping  matrix 
such  that  a  rectangular  region  may  be  referenced  with  a  new 
coordinate  system. 

Usage 

(declare  (notype  (gl:map-coordinates  fixnum  fixnum  fixnum 
fixnum  fixnum  fixnum  fixnum  fixnum))) 

(glimap-coordinates  cxl  cyb  cxr  cyt  nxl  nyb  nxr  nyt) 

where: 

1.  cxl  cyb  cxr  cyt  defines  the  region  in  the  current 
coordinates. 

Dxl  nyb  nxr  nyt  defines  the  region  in  the  new 
coordinates. 

Notes 
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Description 

The  gl:map-standatd-coordinates  function  modifies  the  current 
mapping  matrix  such  that  a  rectangular  region  may  be  referenced 
by  X  and  y  coordinates  whose  values  range  between  0.0  and  1.0. 


Usage 

(declare  (notype  (gl:map-standard-coordinates  flonum  flonum 
flonum  flonum))) 

(glimap-standard-coordinates  xl  yb  xr  yt) 


where : 

1.  xl  Yl  define  the  rectangular  region. 

Notes 


See  the  gl; map-coordinates  function 


Description 

The  gl;mod$  function  computes  the  "remainder 
point  division. 

Usage 

(declare  (flonum  (gl;mod$  flonum  flonum) ) ) 

(gl:mod$  dividend  divsor) 

where: 

1.  dividend  is  the  dividend. 

2.  divsor  is  the  divsor. 

3.  return  value  is  the  remainder. 

Example 


(gl:mod$  1.2  .8)  returns  .4 


qltmov 

Description 

The  gltmov  function  sets  the  CAP. 
Usage 

(declare  (notype  (gl:mov  x  y) ) ) 

(glzmov  X  y) 

where; 

X  is  the  new  x  position, 
y  is  the  new  y  position. 


qltmov 


ql;movrel  gliroovrel 

Description 

The  gl;inovrel  function  sets  the  CAP  relative  to  the  the 
current  one. 

Usage 

(declare  (notype  (gl;movrel  flonum  flonum) ) ) 

(gl:movrel  dx  dy) 
where: 

1.  ^  is  the  relative  x  distance  from  the  current  CAP  to 

the  new  one. 


2.  ^  is  the  relative  y  distance  from  the  current  CAP  to 

th  new  one. 


gl ; point 
Description 

The  gltpoint  function  draws  a  point  at  the  CAP 
Usage 

(declare  (notype  (gltpoint))) 

(gltpoint) 
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gl; ref lect-x  gl; ref lect-x 

Description 

The  gl: ref lect-x  functions  modifies  the  current  mapping 
matrix  such  that  points  are  reflected  about  an  x-axis. 

Usage 

(declare  (notype  (gl; ref lect-x  flonum) ) ) 

(gl: ref lect-x  x) 
where; 

1.  X  defines  the  x  axis. 

Notes 


See  the  gl;reflect-y  function 


Descr iption 

The  gl:reflect-y  function  modifies  the  current  mapping  matrix 
such  that  points  are  reflected  about  a  y  axis. 

Usage 

(declare  (notype  (gl; ref lect-y  f lonum) ) ) 

(gl; ref lect-y  y) 
where; 

1.  Y.  defines  the  y  axis. 


Notes 


See  the  gl;reflect-x  function. 


The  gl; restore-coordinates  function  sets  the  current  mapping 
matrix  to  the  specified  matrix. 

Usage 

(declare  (notype  (gl: restore-coordinates  notype))) 

(gl: restore-coordinates  matrix) 
where: 

1.  matrix  is  a  mapping  matrix,  typically  one  returned  from 
the  gl: save-coordinates  function. 

Notes 


See  the  gl: save-coordinates  function. 


•  ^  ^  ^  ^  ^  iTf 


ql; save-coordinates  gl; save-coordinates 

Description 

The  gl: save-coordinates  function  returns  a  copy  of  the 
current  mapping  matrix. 

Usage 

(declare  (notype  (gl: save-coordinates) ) ) 

(gl: save-coordinates) 

Notes 


See  the  gl: restore-coordinates  function. 


gl; set-coordinates  ql; set-coordinates 

Descr iption 

The  gl: set-coordinates  function  sets  the  mapping  matrix  such 
that  the  screen  is  referenced  by  a  specified  coordinate  system. 

Usage 

(declare  (notype  (gl:  set-coordinates  flonum  flonum  flonum 
f lonum) ) ) 

(gl: set-coordinates  xl  yb  xr  yt) 
where: 

1.  xl ,  yb,  xr ,  yt  defines  the  screen  region. 

Notes 


See  the  gl; set-standard-coordinates  function. 


gl: set-standard-coordinates  gl; set-standard-coordinates 

Description 

The  gl: set-standard-coordinates  function  sets  the  mapping 
matrix  such  that  the  screen  is  referenced  by  x  and  y  values 
ranging  between  0.0  and  1.0. 

Usage 

(declare  (notype  (gl: set-standard-coordinates)  )  ) 

(gl: set-standard-coordinates) 

Notes 


See  the  gl : set-standard-coordinates  function. 


1: solidbox 


1; solidbox 


Descr iption 

The  gl: solidbox  function  draws  a  filled  in  rectangle.  One 
corner  of  the  rectangle  is  at  the  CAP,  and  the  opposite  corner  is 
at  a  specified  position. 

Usage 

(declare  (notype  (glisolidbox  flonum  f lonum) ) ) ) 

(gl; solidbox  x  y) 
where : 

1.  X  is  the  X  coordinate  of  the  corner  opposite  the  CAP. 

2.  Y  is  the  y  coordinate  of  the  corner  opposite  the  CAP. 

Notes 


The  CAP  is  unchanged. 


ql; solidboxrel  gl ; solidboxrel 

Description 

The  gl: solidboxrel  function  draws  the  perimeter  of  a 
rectangle.  One  corner  of  the  rectangle  is  at  the  CAP,  and  the 
opposite  corner  is  determined  by  the  length  of  the  rectangle's 
sides. 

Usage 

(declare  (notype  (gl: solidboxrel  flonum  flonum) ) ) 

(gl: solidboxrel  dx  dy) 


where: 

1.  ^  is  the  length  of  the  horizontal  side. 

2,  ^  is  the  length  of  the  vertical  side. 

Notes 

The  CAP  is  unchanged. 

Dx  and  dy  may  be  negative. 
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gl; solidcircle  gl; solidcircle 

Description 

The  glrcircle  function  draws  a  solid  circle.  The  center  of 
the  circle  is  the  CAP. 

Usage 

(declare  (notype  (gl: solidcircle  f lonum) ) ) 

(gl: solidcircle  radius) 
where: 

1.  radius  is  the  radius  of  the  circle. 

Notes 


The  CAP  is  unchanged 


ql; transform-coordinate  ql; transform-coordinate 

Description 

The  gl: transform-coordinate  function  transforms  a  coordinate 
from  one  coordinate  system  to  another. 

Usage 

(declare  (notype  (gl : transform-coordinate  flonum  flonum 
f lonum  flonum  flonum) ) ) 

(gl; transform-coordinate  old  old2  new  new2  old-coordinate) 
where; 

1.  old  maps  into  new. 

2.  old2  maps  into  new2. 

3.  old-coordinate  is  the  value  to  be  mapped  into  the  new 
coordinate  system. 


4.  return  value  is  the  mapped  value  of  old-coord. 


Description  I  " 

- C - 

The  glrwritetext  function  writes  a  string  of  text  at  the  CAP 
Usage 

(declare  (notype  (gl : wr itetext  notype  notype))) 

(g 1 : wr i tetext  text  horizontal  vertical) 


where ; 

text  is  the  string  to  be  written. 

hor i zontal  controls  the  horizontal  alignment  of  the 
text  string  relative  to  the  CAP.  The  choices  are  "left" 
(text  to  the  left  of  the  CAP),  "center",  or  "right". 

vertical  controls  the  vertical  alignment  of  the  text 
string  relative  to  the  CAP.  The  choices  are  "above" 
(text  above  CAP),  "center",  and  "below". 


Turtle  Graphics  Interface 


back  back 

Description 

The  back  function  causes  the  turtle  to  move  backwards  on  the 
current  heading. 

Usage 

(declare  (notype  (back  flonum) ) ) 

(back  distance) 
where ; 

1.  distance  is  the  distance  to  move  backwards. 


Description 

The  box  function  draws  the  perimeter  of  a  rectangle. 
Usage 

(declare  (notype  (box  flonum  f lonum) ) ) 

(box  dx  dy) 
where; 

dx  is  the  length  of  the  horizontal  side. 
dy  is  the  length  of  the  vertical  side. 

Notes 

The  current  turtle  heading  and  position  are  unchanged 


Dx  and  dy  may  be  negative 


circle 


circle 


Description 

The  circle  function  draws  the  perimeter  of  a  circle.  The 
current  turtle  position  is  the  center  of  the  circle. 

Usage 

(declare  (notype  (circle  f lonum) ) ) 

(circle  radius) 
where: 

1.  radius  is  the  radius  of  the  circle. 

Notes 


The  current  turtle  position  and  heading  are  unchanged. 


clearscreen 


clearscreen 


Description 

The  clearscreen  function  clears  the  screen  to  the  current 
screencolor,  and  homes  the  turtle. 

Usage 

(declare  (notype  (clearscreen))) 

(clearscreen) 

where: 

Notes 

See  the  home  function. 

Clearscreen  sets  the  AED  write  mask  to  2b5 ,  so  all  eight 
memory  planes  will  be  cleared  and  write  enabled. 


forward 


forward 


Description 

The  forward  function  causes  the  turtle  to  move  forward  on  the 
current  heading. 

Usage 

(declare  (notype  (forward  f lonum) ) ) 

(forward  distance) 
where: 

1.  distance  is  the  distance  to  move  forwards. 


heading  heading 

Description 

The  heading  function  returns  the  value  of  the  free  variable 
heading",  which  is  the  direction  of  the  turtle  in  degrees. 

Usage 

(declare  (flonum  (heading))) 

(heading) 
where : 

return  value  is  the  current  heading  in  degrees. 


1. 


hidetur tie 


hideturtle 


Description 

The  hideturtle 
invisible. 

Usage 

(declare  (notype 
(hideturtle) 


function  causes 


(hideturtle) ) ) 


the  turtle  cursor  to  become 


where: 

1.  return  value  is  the  value  of  the  free  variable 
"turtlestate"  just  prior  to  the  hideturtle  call. 


Notes 


See  the  showturtle  function 
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home 


home 


Description 

The  home  function  puts  the  turtle  at  its  initial  position, 
the  center  of  the  screen.  It  is  equivalent  to  "(setturtle  "’(0.5 
0.5  0.0) ) ". 

Usage 

(declare  (notype  (home) ) ) 

( home ) 
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inittur tie 


initturtle 


Description 

The  initturtle  function  initializes  the  turtle  graphics 
system  and  should  be  called  at  the  beginning  of  a  session. 

Usage 

(declare  (notype  (initturtle))) 

( initturtle) 

Notes 

Initturtle  clears  the  screen  to  black,  and  sets  the  turtle 
state  as  follows: 

(setq  heading  0.0  pencolor  'white  penstate  t  screencolor 
'black  turtlestate  t  xcoord  .5  ycoord  .5) 


killturtle 


killturtle 


Description 

The  killturtle  function  cleans  up  the  mess  that  turtles  leave 
around  and  should  be  called  at  the  end  of  a  session. 

Usage 

(declare  (notype  (killturtle))) 

(killturtle) 

Notes 

It  only  hurts  for  a  second. 


pencolor  pencolor 

Description 

The  pencolor  function  returns  the  value  of  the  free  variable 
"pencolor " . 

Usage 

(declare  (notype  (pencolor))) 

(pencolor ) 
where: 

1.  return  value  is  "pencolor". 


pendown  pendown 

Description 

The  pendown  function  changes  the  turtle  state  so  that 
subsequent  moves  will  leave  a  trace  in  the  current  pencolor. 


Usage 

(declare  (notype  (pendown) ) ) 

(pendown) 

where; 

1.  return  value  is  the  value  of  the  free  variable 
"penstate"  prior  to  the  pendown  call. 


penstate  penstate 

Descr iption 

The  penstate  function  returns  the  value  of  the  free  variable 
penstate" . 

Usage 

(declare  (notype  (penstate))) 

(penstate) 

where: 

1.  return  value  is  "penstate". 
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penup 


penup 


Descr iption 

The  penup  function  changes  the  turtle  state  so  that 
subsequent  moves  will  not  leave  a  trace  in  the  current  pencolor. 

Usage 

(declare  (notype  (penup) ) ) 


(penup) 

where; 

1.  return  value  is  the  value  of  the  "penstate"  free 
variable  prior  to  the  penup  call. 
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rad-dei 


rad-deq 

Description 

The  rad-deg  function  converts  radians  to  degrees. 
Usage 

(declare  (flonum  (rad-deg  f lonum) ) ) 

(rad-deg  angle) 
where: 

angle  is  measured  in  radians. 
return  value  is  the  angle  in  degrees. 

Notes 

See  the  deg-rad  function. 


Descr iption 

The  screencolor  function  returns  the  value  of  the  free 
variable  "screencolor". 

Usage 

(declare  (notype  (screencolor))) 

( screencolor) 
where ; 


1 


return  value  is  "screencolor". 


setheadin' 
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setheadinq 

Description 

The  setheading  function  sets  the  turtle  direction. 
Usage 

(declare  (notype  (setheading  f lonum) ) ) 

(setheading  direction) 
where: 

direction  is  the  new  direction  in  degrees. 
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setpencolor 


setpencolor 


Description 

The  setpencolor  function  sets  the  color  the  pen  will  draw 
with  when  down. 


Usage 


(declare  (notype  (setpencolor  notype) ) ) 


(setpencolor  color) 


where: 


1.  color  is  an  atom  whose  print  name  is  the  desired  color. 

2.  return  value  is  the  pencolor  just  prior  to  the 
setpencolor  call. 


Notes 


Pencolors  currently  supported  are  black,  red,  green,  yellow, 
blue,  magenta,  cyan,  and  white. 


setscreencolor  setscreencolor 

Description 

The  setscreencolor  function  sets  the  color  that  the  screen 
will  be  cleared  to  after  a  call  to  the  "clearscreen"  function. 

Usage 

(declare  (notype  (setscreencolor  notype))) 

(setscreencolor  color) 
where; 

1.  color  is  an  atom  whose  print  name  is  the  desired  color. 

2.  return  value  is  the  screencolor  just  prior  to  the 
setscreencolor  call. 


Notes 

Screencolors  currently  supported  are  black,  red,  green, 
yellow,  blue,  magenta,  cyan,  and  white. 
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setturtle 


setturtle 


Description 

The  setturtle  function  sets  the  turtle  coordinates  and 
heading. 

Usage 

(declare  (notype  (setturtle  notype) ) ) 

(setturtle  list) 
where: 

1.  list  is  (x  y  heading). 

Notes 

See  the  here  function. 

If  the  pen  is  down,  a  trace  will  be  left. 


setx 


setx 


Description 

The  setx  function  sets  the  turtle  x  coordinate  (the  free 
variable  "xcoord") . 

Usage 

(declare  (notype  (setx  f lonum) ) ) 

(setx  x) 
where: 

1.  X  is  the  new  x. 


showturtle 


showturtle 


Description 

The  showturtle  function  causes  the  turtle  cursor  to  become 
visible. 

Usage 

(declare  (notype  (showturtle))) 

(showturtle) 

where: 

1.  return  value  is  the  value  of  the  free  variable 
"turtlestate"  just  prior  to  the  showturtle  call. 

Notes 

See  the  hideturtle  function. 


solidbox 


solidbox 


Description 

The  solidbox  function  draws  a  filled  in  rectangle. 
Usage 

(declare  (notype  (solidbox  flonum  flonum) ) ) 

(solidbox  dx  dy) 
where: 

dx  is  the  length  of  the  horizontal  side. 
dy  is  the  length  of  the  vertical  side. 

Notes 

The  current  turtle  position  and  heading  are  unchanged. 
Dx  and  dy  may  be  negative. 


solidcircle 


solidcircle 


Description 

The  solidcircle  function  draws  a  filled  in  circle.  The 
current  turtle  position  is  the  center  of  the  circle. 

Usage 

(declare  (notype  (solidcircle  f lonum) ) ) 

(solidcircle  radius) 
where; 

1.  radius  is  the  radius  of  the  solidcircle. 


Note 

Current  turtle  position  and  heading  are  unchanged. 


turtlestate 


turtlestate 


Description 

The  turtlestate  function  returns  the  value  of  the  free 
variable  "turtlestate",  which  describes  whether  the  turtle  is  up 
or  down. 

Usage 

(declare  (notype  (turtlestate))) 

( turtlestate) 
where; 

1.  return  value  is  "turtlestate". 


Notes 


Turtlestate  is  "t"  if  the  pen  is  down, 


nil"  if  the  pen  is 


xcoord 


xcoord 


Description 

Usage 

(declare  (notype  (xcoord))) 

(xcoord) 
where : 

return  value  is  the  turtle  x  position. 


ycoord 

Description 

Usage 

(declare  (notype  (ycoord))) 

(ycoord) 
where : 

return  value  is  the  turtle  y  position. 


ycoord 
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elo: button-read 


elo: button-read 


Description 


The  elo: button-read  function  divides  the  touch  screen  into 
four  quadrants,  and  associates  a  button  value  with  each. 

Usage 

(declare  (notype  (elo:button-read) ) ) 


(elo: but ton- re ad) 
where: 

1.  return  value  is  "t",  if  the  Biographies  is  alive,  "nil" 
otherwise. 

2.  *g i ; button-val*  is  a  free  variable  SETQed  to  "0"  if  the 
screen  is  not  being  touched,  "1"  if  the  upper  right 
quadrant  is  being  touched,  "2"  if  the  upper  left 
quadrant  is  being  touched,  "4"  if  the  lower  left  button 
is  being  touched,  and  "8"  if  the  lower  right  quadrant 
is  being  touched. 


elo: locator-read 


elo: locator-read 


Description 

The  elo: locator  function  reads  the  position  of  a  finger  on 
the  surface  of  the  Biographies. 

Usage 

(declare  (notype  (elo: locator) ) ) 

(elo: locator ) 
where: 

1.  return  value  is  "t"  if  a  finger  is  touching  the 
surface,  "nil"  otherwise. 

*gi : locator-x*  ,  *gi : locator-y*  are  free 
SETQed  to  the  x  and  y  position  of  the  finger. 


2. 


variables 


The  gi; button-change  function  polls  the  current  button  device 
until  it  returns  a  value  different  from  the  one  specified. 

Usage 

(declare  (notype  (gi; button-change  fixnum) ) ) 

(gi; button-change  oldval) 
where; 


1.  oldval  is  the  value  that  the  button  value  must  be 
different  from. 


The  gi; button-pr int  function  is  an  infinite  loop  which  prints 
the  values  returned  by  the  gi:button-read  function. 

Usage 

(declare  (notype  (gi:button-print  notype) ) ) 

(gi :  button-pr  int  dear-flag) 
where: 

!•  dear-flag  if  non-nil,  gi:button-clear  will  be  called 
before  gi: button-read  each  time  in  the  loop. 


Notes 
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gi; button-read  gi; button-read 

Description 

The  gi : button-read  function  calls  the  current  button  device. 


K 


Usage 

(declare  (notype  (gi: button-read) ) ) 
(gi: button-read) 


where: 

1.  return  value  is  the  status  returned  by  the  current 
button  function. 

2.  *gi : button-val*  is  a  free  variable  which  is  SETQed  by 
thi 


le  current  button  function. 


Notes 


See  the  gi: select-button  and  gi: select-device  functions, 
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gi;  but ton- trap  qi; button-trap 

Description 

The  gi: button-trap  function  polls  the  current  button  device 
until  it  returns  the  specified  value. 

Usage 

(declare  (notype  (gi: button-trap  f ixnum) ) ) 

(gi: button-trap  newval) 
where: 


1.  newval  is  the  value  the  current  button  device  must 
return. 


Description 

The  gi; locator-latch  function  polls  the  locator  and  button 
devices  alternatly  until  the  sequence  of  button  values  "0", 
"non-zero",  and  "0"  are  reported.  The  most  recent  position  of  the 
locator  device  is  available  when  the  function  returns. 

Usage 

(declare  (notype  (gi; locator-latch) ) ) 

(gi: locator-latch) 
where; 

1.  *qi ; locator-x* ,  gi; locator-y*  are  SETQed  to  the  locator 
position. 

Notes 


See  the  gi; track  function. 


i; locator-print 


Description  ; 

I 

The  gi: locator-print  function  is  an  infinite  loop  which  j 

prints  the  values  returned  by  gi: locator-read.  i 

I 

I 

Usage 

(declare  (notype  (gi: locator-print  notype)))  ‘ 

(gi:  locator-print  dear-flag)  *  j 

where: 

1.  dear-flag  if  non-nil/  gi:  locator-clear  will  be  called 
before  gi: locator-read  each  time  in  the  loop. 

Notes 


Use  cntl-G  to  stop. 
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gi ; locator-read  qi ; locator-read 

Description 

The  gi : locator-read  function  calls  the  current  locator 
device. 

Usage 

(declare  (notype  (gi : locator-read) ) ) 

(gi; locator-read) 
where ; 

1.  return  value  is  the  status  returned  by  the  locator 
function. 

2.  *gi; locator-x* ,  *qi ; locator-y*  are  free  variables 

SETQed  by  the  locator  function. 

Notes 


See  the  gi : select-locator  and  gi; select-device  functions 


Description 

The  gi: locator-trap  function  waits  for  the  locator  device  to 
return  "t". 


Usage 

(declare  (notype  (gi: locator-trap) ) ) 
(gi: locator-trap) 
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L  i ; select-button 


ti: select-button 


Description 

The  gi; select-button  function  selects  the  function  that  will 
be  used  to  read  button  values. 


Usage 


(declare  (notype  (gi; select-button  notype))) 

(gi; select-button  device) 
where; 

1.  device  is  an  atom  whose  name  is  the  device  to  be  used. 

2.  device; button  will  be  the  function  that  gi; button-read 
calls . 

3.  return  value  is  "t"  if  the  select  was  successful,  "nil" 
otherwise . 

Notes 

Currently  supported  button  devices  are  "aed",  "clOO",  "elo", 
"keyboard",  and  "summa". 
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Description 

The  gi: select-device  function  selects  a  device  to  act  both  as 
button  and  locator. 

Usage 

(declare  (notype  (gi: select-device  notype))) 

(gi: select-device  device) 
where: 

1.  device  is  an  atom  whose  name  is  the  device  to  be  used. 

2.  return  value  is  "t"  if  the  select  was  sucessfull,  "nil" 
otherwise. 

Notes 


Currently  supported  devices  are  "aed",  "clOO",  "elo", 
"keyboard",  and  "summa". 


See  the  gi: select-button  and  gi;select-locator  functions 


Description 

The  gi; select-locator  function  selects  the  function  that  will 
be  used  to  read  locator  values. 

Usage 

(declare  (notype  (gi: select- locator  no type) ) ) 

(gi: select- locator  device) 
where : 

1.  device  is  an  atom  whose  name  is  the  device  to  be  used. 

2.  device: locator  is  the  function  that  gi: locator-read 
will  call. 

3.  return  value  is  "t"  if  the  select  was  sucessful,  "nil" 
otherwise. 

Notes 

Currently  supported  locator  devices  are  "aed",  "clOO",  "elo", 
"keyboard",  and  "summa". 


qi; track  gi; track 
Descr iption 

The  gi: track  function  will  continuously  display  the  position 
of  the  locator  device  by  using  the  A.ED  cursor.  The  function 
terminates  (and  the  AED  cursor  is  turned  off)  when  the  button 
device  has  reported  a  sequence  of  "0",  "nonzero",  and  "0"  values. 


Usage 


(declare  (notype  (gi;track))) 

(gi: track) 
where: 

1.  *qi; Iqcator-x* ,  *qi; locator-y*  are  free  variables 
SETQed  to  the  last  xy  position  the  locator  device 
reported  before  the  function  terminated. 


Notes 


See  the  gi: locator-latch  function. 


suinina:  button-read 


sunrnia:  button-read 


Description 

The  summa; button-read  function  reads  the  four  buttons  on  top 
of  the  Summagraphics  puck. 

Usage 


(declare  (notype  ( sununa: button-read) ) ) 

( summa: button-read) 
where: 

1.  return  value  is  "t",  if  the  Summagraphics  is  alive. 


"nil"  otherwise. 

(If  the 

puck  is 

j  j. 

not  on 

the  tablet 

surface,  "nil"  will 

be  returned.) 

2.  *qi: button-val*  is 

SETQed 

to  "0" 

if  no 

button  is 

pressed,  "1"  if  the  yellow  button  is  pressed,  "2"  if 
the  white  button  is  pressed,  "4"  if  the  blue  button  is 
pressed,  and  "8"  if  the  green  button  is  pressed. 


suirana; locator-read 


sununa:  locator-read 


Description 

The  sununa: locator-read  function  reads  the  position  of  the 
puck  on  the  tablet  of  the  Sununagraphics. 

Usage 

(declare  (notype  (sununa: locator-read) ) ) 

(sununa:  locator-read) 
where: 

1.  return  value  is  "t",  if  the  Sununagraphics  is  alive, 
'‘nil"  otherwise.  (If  the  puck  is  not  on  the  tablet 
surface,  "nil"  will  be  returned.) 

2.  *gi: locator-x* ,  *qi: locator-y*  are  free  variables 
SETQed  to  the  x  and  y  position  of  the  puck. 


